usage-stats

usage-stats

A minimal, offline-friendly Google Analytics Measurement Protocol client for tracking usage statistics in node.js applications.

This is only a low-level client API, it doesn't hold any opinion of how usage tracking should be done. If you're looking for a convention which leverages the power and flexibility of Custom Metrics and Dimensions, take a look at track-usage.

Synopsis

Simple

The most trivial example.

const UsageStats = require('usage-stats')
const usageStats = new UsageStats('UA-98765432-1')

// track a hit on the 'main' screen with 'simple' mode set.
usageStats
  .screenView('main')
  .event('option', 'mode', 'simple')
  .send()

Typical

More realistic usage in an example video encoding app.

const UsageStats = require('usage-stats')
const usageStats = new UsageStats('UA-98765432-1', {
  name: 'enocode-video',
  version: '1.0.0'
})

// start a new session
usageStats.start()

// user set two options..
usageStats.event('option', 'verbose-level', 'infinite')
usageStats.event('option', 'preset', 'iPod')

try {
  // Begin. Track as a screenView.
  usageStats.screenView('encoding')
  beginEncoding(options)
} catch (err) {
  // Exception tracking
  usageStats.exception(err.message, true)
}

// finished - mark the session as complete
// and send stats (or store if offline).
usageStats.end().send()

Parameters

See here for the full list of Google Analytics Measurement Protocol parameters.

Sent by default

All parameters are send on demand, beside this list.

• Operating System version (sent in the UserAgent)
• Client ID (a random UUID, generated once per OS user and stored)
• Language (process.env.LANG, if set)
• Screen resolution (terminal rows by columns, by default)

API Reference

Kind: inner class of UsageStats
Extends: usage-stats

• ~UsageStatsAbortable ⇐ usage-stats
  • .send([options])
  • .abort() ↩︎
  • .start([sessionParams]) ↩︎
  • .end([sessionParams]) ↩︎
  • .disable() ↩︎
  • .enable() ↩︎
  • .event(category, action, [options]) ⇒ Map
  • .screenView(name, [options]) ⇒ Map
  • .exception(description, isFatal) ⇒ Map
  • .debug() ⇒ Promise

usage.send([options])

Kind: instance method of UsageStatsAbortable
Overrides: send

Param	Type
[options]	object
[options.timeout]	number

usage.abort() ↩︎

Aborts the in-progress .send() operation, queuing any unsent hits.

Kind: instance method of UsageStatsAbortable
Chainable

usage.start([sessionParams]) ↩︎

Starts the session.

Kind: instance method of UsageStatsAbortable
Chainable

Param	Type	Description
[sessionParams]	Array.<Map>	An optional map of paramaters to send with each hit in the sesison.

usage.end([sessionParams]) ↩︎

Ends the session.

Kind: instance method of UsageStatsAbortable
Chainable

Param	Type	Description
[sessionParams]	Array.<Map>	An optional map of paramaters to send with the final hit of this sesison.

usage.disable() ↩︎

Disable the module. While disabled, all operations are no-ops.

Kind: instance method of UsageStatsAbortable
Chainable

usage.enable() ↩︎

Re-enable the module.

Kind: instance method of UsageStatsAbortable
Chainable

usage.event(category, action, [options]) ⇒ Map

Track an event. All event hits are queued until .send() is called.

Kind: instance method of UsageStatsAbortable

Param	Type	Description
category	string	Event category (required).
action	string	Event action (required).
[options]	option
[options.label]	string	Event label
[options.value]	string	Event value
[options.hitParams]	Array.<map>	One or more additional params to send with the hit.

usage.screenView(name, [options]) ⇒ Map

Track a screenview. All screenview hits are queued until .send() is called. Returns the hit instance.

Kind: instance method of UsageStatsAbortable

Param	Type	Description
name	string	Screen name
[options]	object
[options.hitParams]	Array.<map>	One or more additional params to set on the hit.

usage.exception(description, isFatal) ⇒ Map

Track a exception. All exception hits are queued until .send() is called.

Kind: instance method of UsageStatsAbortable

Param	Type	Description
description	string	Error message
isFatal	boolean	Set true if the exception was fatal
[options.hitParams]	Array.<map>	One or more additional params to set on the hit.

usage.debug() ⇒ Promise

Send any hits (including queued) to the GA validation server, fulfilling with the result.

Kind: instance method of UsageStatsAbortable
Fulfil: Response[]
Reject: Error - Error instance includes hits.

---

© 2016 Lloyd Brookes <[e-mail]>. Documented by jsdoc-to-markdown.